Tentative on this, majority of our docs are in CJS and the underlying code is in CJS.

@Fdawgs would you not agree that Modules is the way node is headed and the majority of new code is written with modules? I understand that the underlying code is in CJS (and other parts of the docs too) but that wouldn't be a deterrent. If we want to move forward change needs to be incremental and non-breaking! We couldn't possibly update it all at once :)

Tentative on this, majority of our docs are in CJS and the underlying code is in CJS.

Likewise, CJS is still the default for Node in that it will treat all .js files as cjs unless the type is explicitly set to module in package.json.

I agree with this.

Also, each example, considering the diff only, seems to be completely stand alone prior to this proposed change. With this change, each example, subsequent to the first, references a missing variable.

Tentative on this, majority of our docs are in CJS and the underlying code is in CJS.

@Fdawgs would you not agree that Modules is the way node is headed and the majority of new code is written with modules? I understand that the underlying code is in CJS (and other parts of the docs too) but that wouldn't be a deterrent. If we want to move forward change needs to be incremental and non-breaking! We couldn't possibly update it all at once :)

Maybe. Maybe not. Personally, I find ESM way more trouble than it's worth and a frustrating syntax full stop. So I rarely ever use it. The most common case being to get top level await, but I'd rather wrap everything in an async function than deal with ESM just for that.

Thank you for sharing your perspective @jsumners, I didn't know this would be so polarizing!
The example on the readme over on fastify/fastify is also using ESM Imports, so it just made sense to me that the endorsed plugins would also follow suit :)
As for the argument "the rest of our docs are in cjs", this would imply that the right thing to do would be for this PR to be extended to cover all existing docs, something that I don't have the time for.

I'm unsure what you mean by:

With this change, each example, subsequent to the first, references a missing variable.

What missing variable are you referring to?

Thank you for sharing your perspective @jsumners, I didn't know this would be so polarizing!

Note that I have not submitted a review. Thus I have not cast a vote one way or the other.

The example on the readme over on fastify/fastify is also using ESM Imports, so it just made sense to me that the endorsed plugins would also follow suit :)

I think the main repo provides both CJS and ESM through a toggle while viewing the website.

What missing variable are you referring to?

The multipart identifier.

What missing variable are you referring to?

The multipart identifier.

@jsumners The subsequent examples are also missing the fastify, fs and pipeline definitions though :)

The example on the readme over on fastify/fastify is also using ESM Imports, so it just made sense to me that the endorsed plugins would also follow suit :)

The fastify/fastify repository’s README provides both ESM and CommonJS examples (please see attached).
If this change is intended to align with the README, it might be nice to include both ESM and CommonJS examples here as well.

https://github.com/fastify/fastify?tab=readme-ov-file#example

I agree that having ESM examples is important. It’s the default for most frontend tools and is also adopted by many Node.js frameworks, such as Nest.js and Next.js.

That said, the most widely used Node.js framework, Express, still documents examples in CJS, and this doesn't seem to be an issue in practice.

Although I personally use ESM, I believe consistency and ease of maintenance is more important here. I see a few possible approaches:

1. Keep CJS examples - by far the easiest option for us to maintain.

2. Add both CJS and ESM examples in every repo. More complete, but doubles the documentation examples.

3. Replace all CJS examples with ESM. Consistent with newer tools, but Fastify’s doesn't come with an ESM boiterplate by default. If a user only run npm i fastify, the project uses CJS by default.
   That's said recent Node versions will trigger a meaningful warning, not an error:

[MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of is not specified and it doesn't parse as CommonJS.